home *** CD-ROM | disk | FTP | other *** search
/ Archive Magazine CD 1995 / Archive Magazine CD 1995.iso / discs / pipeline / abacus / p_line / Custom02 / ReadMe < prev   
Encoding:
Text File  |  1992-08-08  |  15.8 KB  |  320 lines
  1. %OP%VS4.13 (28-Apr-92), Gerald L Fitton, R4000 5966 9904 9938 
  2. %OP%DP0
  3. %OP%IRY
  4. %OP%PL0
  5. %OP%HM0
  6. %OP%FM0
  7. %OP%BM0
  8. %OP%LM4
  9. %OP%FX160
  10. %OP%FY160
  11. %OP%FS10000
  12. %OP%PT1
  13. %OP%PDPipeLine
  14. %OP%WC1026,2262,184,1748,0,0,0,0
  15. %CO:A,72,72%
  16. %C%Custom Functions from the Beginning - Part 2
  17. %C%by Gerald L Fitton
  18. Keywords:
  19. 4ProL Custom Function Variables Sequence Fitton
  20.  
  21. Introduction to '4ProL'
  22. This is the second tutorial article of a series which, I hope, will 
  23. help you to get to grips with one of the new features of PipeDream 4, 
  24. custom functions.  The first part of the series is in the directory 
  25. Custom01 and the [ReadMe] file describes how a custom function is 
  26. 'called' and how it can 'return' a value.  If you wish to use custom 
  27. functions then you need to learn '4ProL', the PipeDream 4 custom 
  28. function programming language.
  29.  
  30. Let's see a custom function at work.  If you have a deep screen mode 
  31. then it is preferable to use it because it will make it easier to see 
  32. substantial parts of the custom function without losing the document 
  33. which 'calls' it.  If not, then you will have to use mode 12 and scroll 
  34. through the documents as is necessary.  I am using the Atomwide VIDC 
  35. mode 102 with an Eizo 9070S multiscan and an A540 Archimedes.  This 
  36. monitor-mode combination has a screen depth of over 50 lines and a 
  37. screen width of over 130 system font characters when using PipeDream.  
  38. Mode 12 is about half that width and depth, a quarter of the area!
  39.  
  40. Double click on the file [Add] and you will find that you load to the 
  41. screen not only [Add] but a dependent document which I have called 
  42. [c_Add] containing three custom functions.  I would have liked to make 
  43. [c_Add] wider but I have deliberately limited its width to 72 
  44. characters so that it will fit a mode 12 screen.  To keep within 72 
  45. characters I have had to use short names such as "p_01" for the 
  46. variables.  This is not good programming practice.  I would have 
  47. preferred to use a long meaningful name such as "first_parameter".
  48.  
  49. Because PipeDream 4 saves the position of a PipeDream document on the 
  50. screen and the position of the cursor within the document, what you 
  51. should find is that [Add] is visible and alive (a yellow top bar) with 
  52. the cursor in slot [Add]B7.  If not then position the pointer on the 
  53. number in [Add]B7 (it should be the number 2 unless you've modified the 
  54. file) and click the mouse select (left) button.  You should see the 
  55. same number in the formula line (at the top of the document just to the 
  56. right of the cross and tick).  Tap some other number, say 9, and then 
  57. tap <Return>.  If all goes well then, as well as [Add]B7 changing to 9, 
  58. all three numbers in the range [Add]B10 to [Add]B12 increase.
  59.  
  60. For the moment we are going to concentrate on the custom function 
  61. 'called' from [Add]B10.  It is not a spectacular custom function.  The 
  62. 'result' returned to the slot [Add]B10 is (B7 + 1), one more than the 
  63. number in the slot [Add]B7.  Change the value in [Add]B7 a few times 
  64. and convince yourself that the value in [Add]B10 is always 1 more than 
  65. the value in [Add]B7.
  66.  
  67. Now let's have a look at the content of slot [Add]B10.  Place the 
  68. pointer over [Add]B10 and click select.  The formula line does not show 
  69. the simple, non custom function way of adding 1 which would be 
  70. (B7 + 1); instead it shows the formula used to 'call' the custom 
  71. function, namely [c_Add]add_anything(B7).
  72.  
  73. The 'calling' formula is in three parts:
  74.  
  75. The first part - [c_Add] - is the name of the dependent document which 
  76. contains the custom function.
  77.  
  78. The second part - add_anything - is the name of the custom function 
  79. within [c_Add] which you can find in row 22 of the document [c_Add].
  80.  
  81. The third part - (B7) - is the slotref of the single piece of data 
  82. passed to [c_Add] for processing.
  83.  
  84. Returning the result
  85. 'Calling' the custom function - [c_Add]add_anything(B7) - from slot 
  86. [Add]B10 returns the result of the processing to the slot from which it 
  87. was called, [Add]B10.
  88.  
  89. If you place the cursor in [Add]B14 (which shows the number 1) you will 
  90. find that the formula line (just to the right of the cross and tick) 
  91. shows that the slot contains another 'call' to the same custom function 
  92. - [c_Add]add_anything(0) - but, instead of the parameter being a 
  93. slotref, it is the value 0.  You can change the parameter (0) to (9) in 
  94. the formula line; when you tap <Return> you will find that the custom 
  95. function returns the 'result', 10 to the slot, [Add]B14, from which it 
  96. was called.  The number returned is always one greater than the number 
  97. passed as a parameter to the custom function.
  98.  
  99. When testing a custom function sometimes it is revealing to 'call' the 
  100. function from a 'spare' slot using not a slotref as the parameter but a 
  101. value you want to test.  We shall return to examples of this aid to 
  102. 'debugging' in a later tutorial.
  103.  
  104. The custom function
  105. What we haven't looked at yet is the custom function itself to see how 
  106. it adds one to the parameter and returns the 'result'.  To do this we 
  107. must bring the custom function - [c_Add]add_anything - into view.
  108.  
  109. Make sure that the cursor is 'in' slot [Add]B7 and then (particularly 
  110. if you are using a 'small' screen mode such as mode 12) bring the 
  111. document [c_Add] to the front but leave [Add] as the document which is 
  112. 'alive' (a yellow top bar).  If the part of [c_Add] which is visible is 
  113. not rows 22 to 39 and columns A to C then use the vertical sliders or 
  114. scroll bars to achieve this.
  115.  
  116. Check that it is [Add] and not [c_Add] or this [ReadMe] which is alive 
  117. and that PipeDream's 'input focus' (where the next character typed will 
  118. appear) is in slot [Add]B7.  After checking, you can confirm this most 
  119. easily by tapping a new number such as 7 followed by <Return>.  If you 
  120. have done everything correctly then you will see that the values in 
  121. slots [c_Add]C28 and [c_Add]C31 change to 7 and 8 respectively.
  122.  
  123. Just as it was possible to add one to the contents of [Add]B7 much more 
  124. simply by entering (B7 + 1) into [Add]B10 instead of entering the 
  125. custom function, so would it have been possible to have simplified the 
  126. custom function itself to just two lines as we did in Custom01.  
  127. However, so that I can illustrate a few features of the '4ProL' 
  128. programming language, I have 'stretched out' the custom function to 
  129. span lines 22 to 39 of [c_Add] and columns A to C.
  130.  
  131. Let's look at the commands in detail and see how they process data.
  132.  
  133. Row 22 - ...function("add_anything","p_01:number")
  134. In this custom function the '4ProL' command - ...function - has two 
  135. arguments.  The first argument is the name of the custom function, 
  136. - "add_anything" - note that the name is included in inverted commas.  
  137. The second argument is the one and only parameter passed to the 
  138. function.  You can pass many parameters each separated by a comma from 
  139. the next one.  The name of every parameter must be enclosed in a pair 
  140. of inverted commas.  If you want to pass a large number of values to a 
  141. custom function then it is 'better' (more understandable) to pass a 
  142. range or array.  The name of the one parameter passed to 
  143. - [c_Add]add_anything - is - p_01 ­ and its 'type' has been declared 
  144. (after the colon) as a number.  Because of this declaration, if you try 
  145. to pass anything other than a number to this function then an error 
  146. will be generated.
  147.  
  148. You do not have to declare the type of variable if you want to pass a 
  149. number sometimes and, say, a string on another occasion.  Try typing 
  150. Fred (with or without inverted commas into [Add]B7 and you will find 
  151. that the error message - String not expected - is returned to slot 
  152. [Add]B10.  You will find the error message foreshortened in the body of 
  153. the [Add] document.  If you want to read the full error message then 
  154. click the pointer in [Add]B10, then on the formula button (the italic f 
  155. just to the right of the PipeDream 4 logo) and finally run the pointer 
  156. through the first menu option - Slot 'B10' - Slot value - and you will 
  157. see the full error message displayed.  This technique is particularly 
  158. useful when long error messages are generated.
  159.  
  160. Row 25 - ...set_value(B25,1)
  161. Here is another convention which I recommend to you.  I am using column 
  162. B as a 'workspace' for my custom function sheets.  One major use for 
  163. this workspace is to 'store' the values of 'local' variables.
  164.  
  165. In this custom function I use slot [c_Add]B25 as storage for a 'local' 
  166. variable.  The 'local' variable is the number which will be added to 
  167. the value taken by the parameter "p_01".  
  168.  
  169. The '4ProL' command - set_value(B25,1) - writes the value 1 to the 
  170. space allocated to the 'local' variable [c_Add]B25.
  171.  
  172. Change the command to - set_value(B25,3) - and the custom function will 
  173. now add 3 to the number passed to it as a parameter.  Remember that the 
  174. custom function is not executed until you 'call' it from [Add]B7 (see 
  175. above how to 'call' it).
  176.  
  177. Now here is something else you can do with this line which allows me to 
  178. introduce the concept of a 'global' variable.
  179.  
  180. Change the command to - set_value(B25,[Add]B8) - and call the custom 
  181. function by changing [Add]B7.  The value which is added to the 
  182. parameter is now the value of the 'global' variable in [Add]B8.  Change 
  183. the value in [Add]B8 and notice that the value 'returned' to [Add]B10 
  184. has not changed.  Are you surprised?  'Call' the custom again by 
  185. changing [Add]B7 and watch what happens.
  186.  
  187. Put [c_Add]A25 back to - set_value(B25,1) - or, if you have problems, 
  188. delete the document and reload it.
  189.  
  190. Row 28 - ...@p_01
  191. This command assigns the current value of the parameter "p_01" to the 
  192. slot [c_Add]A28.  I have included this so that you will see exactly how 
  193. to include parameters in custom functions.  Notice that the inverted 
  194. commas have 'disappeared' and that the name of the parameter is 
  195. preceded by an @@ sign.  The @@ sign converts a numeric parameter to a
  196. number.  See what happens to the parameter if you remove the @@ - the 
  197. three full stops in front of the p_01 disappear.
  198.  
  199. Row 31 - ...@p_01+B25
  200. This '4ProL' command assigns the value of (@p_01+B25) to slot 
  201. [c_Add]A31.  Experiment by changing the plus sign to a minus sign or, 
  202. indeed, any mathematical function of two variables.
  203.  
  204. Rows 34 to 36 - set_value(C28,A28) etc
  205. These three rows are totally unnecessary but, if you do have a problem 
  206. understanding what is going on within a custom function (for example 
  207. if you have a 'bug'), then lines like this are invaluable.  A 
  208. convention which I use for this purpose and which I recommend to you is 
  209. to assign values to the slot in column C corresponding to the values in 
  210. columns A or B.
  211.  
  212. Row 38 - ...result(A31)
  213. The command - ...result - terminates the sequence of commands and 
  214. returns a value to the slot from which it was called, [Add]B10.
  215.  
  216.  
  217. The custom function - [c_Add]use_slots
  218. Use the scroll bars to make lines [c_Add]A58 to [c_Add]A82 visible on 
  219. the screen.  This function is called from [Add]B11 and the 'result' 
  220. which is returned is the sum of the numbers in the two slots [Add]B7 
  221. and [Add]B8.  Note that the two values in these slots are passed as two 
  222. parameters to the custom function.
  223.  
  224. It is bad practice to alter values of a parameter within a custom 
  225. function; one of the most important features of a parameter is that, 
  226. anywhere within the custom function you must be sure that it always 
  227. has the same value.
  228.  
  229. I know that the sum of two parameters can be done very simply with one 
  230. line such as - ...result(@@p_01+@@p_02) - but I have written the short 
  231. program in a way which illustrates the way of declaring 'local' 
  232. variables and altering their values.  In this custom function I add one 
  233. to the first parameter and subtract one from the second.  Of course the 
  234. parameters could be processed in much more complex ways before being 
  235. combined and the 'result' returned to the slot in [Add] from which the 
  236. custom function was called.  
  237.  
  238. The two slots [c_Add]B65 & [c_Add]B66 are used as 'local' variables.  
  239. The values of the two parameters are assigned to these two 'local' 
  240. variables by the commands in slots [c_Add]A65 & [c_Add]A66.  
  241.  
  242. As I indicated above, the reason why I have assigned the values of the 
  243. parameters to two 'local' variables is so that the values can be 
  244. changed.  The commands in slots [c_Add]A69 &[c_Add]A70 do change the 
  245. values of the 'local' variables.
  246.  
  247. The values of the two 'local' variables are added in slot [c_Add]A73.
  248.  
  249. The 'result' is returned by the command in slot [c_Add]A82.
  250.  
  251.  
  252.  
  253. The custom function - [c_Add]use_names
  254. This custom function is called from slot [Add]B12 and uses slots 
  255. [c_Add]A120 to [c_Add]A144.  I have included this function as an 
  256. introduction to the use of a 'name' for a 'local' variable within a 
  257. custom function.  Generally it is preferable to use a 'name' rather 
  258. than a slot (as in [c_Add]use_slots) when a 'local' variable is needed.  
  259. I recommend that you always use 'names' for 'local' variables as I am 
  260. doing here rather than use slots as in the previous custom function.
  261.  
  262. In a custom function a 'local variable name' must be declared only 
  263. once.  It is good programming practice to declare all the local 
  264. variables you are going to use at the beginning of the custom function 
  265. as I have done here.
  266.  
  267. A 'name' is declared with the command - set_name(name,slotref) as it is 
  268. in [c_Add]A123 & [c_Add]A124.  When a 'name' is declared in a custom 
  269. function it is good practice to assign a slot in your workspace (I am 
  270. using column B for my workspace) rather than assign a dummy value to 
  271. the 'name'.  In this case the slots B123 & B124 have been assigned to 
  272. the 'names' "n_01" and "n_02" respectively.  After declaring the 'name' 
  273. of the 'local' variable you may assign a new value to that 'name' as 
  274. many times as you wish using the command - set_value(name,value).  When 
  275. you change the value of a name the value in the slot assigned to that 
  276. name in the workspace will also change.
  277.  
  278. The commands in slots A127 & A128 assign the values of the two 
  279. parameters, "p_01" & "p_02" to the two names "n_01" & "n_02".  Notice 
  280. that when this command is executed new values of the 'names' are 
  281. relayed to and stored in the two slots B123 & B124.  The command in 
  282. A138, - set_value(C123C124,A123A124), is included to show that the 
  283. values in A123 & A124 are not changed by the commands in A127, A128, 
  284. A131 & A132!  However, these last four commands do change the values of 
  285. the two 'local variable names' and the values in the slots B123 & B124.
  286.  
  287. Contrast the use of 'names' in this custom function with the use of 
  288. parameters in "use_slots".  Values such as "p_01" have to be written as 
  289. @@p_01 to become a value whereas the 'name' "n_01" is a value when 
  290. written as n_01.  The command set_name("name",slotref) requires 
  291. inverted commas around the 'name' because, within the set_name command, 
  292. "n_01" is a text string.  The addition, n_01+n_02, in slot A135 does 
  293. not require inverted commas around the 'names' nor do the 'names' need 
  294. to be preceded by @@; n_01 is the value taken by the 'name' "n_01".
  295.  
  296. Summary
  297. A custom function is a sequence of commands which start with a 
  298. - function - command and end with a - result - command.  Once there is 
  299. a custom function within a document then the whole document is a custom 
  300. function document.  Custom function documents behave differently from 
  301. 'ordinary' documents - but they do not have a different file type!
  302.  
  303. Parameters can be passed to custom functions.  They must retain their 
  304. identity and value throughout the custom function.
  305.  
  306. Names should be used for local variables rather than slots.  Use the 
  307. - set_name - command once only to assign a slot in the workspace to the 
  308. local variable name.  Thereafter, to change the value of the local 
  309. variable, the - set_value - command must be used and not the 
  310. - set_name ­ command.
  311.  
  312. The next tutorial
  313. In the next tutorial of this series I will introduce the concept of 
  314. making a decision, "Conditional execution".  In the meantime, if you 
  315. wish to see how local variables are declared with the command
  316. - set_name("name",slotref) - and then how the value of the named local 
  317. variable is changed with set_value("name",value) I suggest that you 
  318. have a look at the rather more advanced custom function you will find 
  319. in a directory Primes on the May 1992 PipeLine 4 disc.
  320.